Security News
Node.js EOL Versions CVE Dubbed the "Worst CVE of the Year" by Security Experts
Critics call the Node.js EOL CVE a misuse of the system, sparking debate over CVE standards and the growing noise in vulnerability databases.
Publish to a gh-pages branch on GitHub (or any other branch on any other remote)
The gh-pages npm package is a utility for deploying projects to GitHub Pages. It simplifies the process of publishing content to a GitHub repository's gh-pages branch, which is used to serve static sites directly from the repository.
Deploying to GitHub Pages
This feature allows you to deploy the contents of a directory (in this case, 'dist') to the gh-pages branch of your repository. The callback function handles any errors that occur during the deployment process.
const ghpages = require('gh-pages');
ghpages.publish('dist', function(err) {
if (err) {
console.error('Deployment failed:', err);
} else {
console.log('Deployment successful!');
}
});
Customizing Deployment
This feature allows you to customize the deployment by specifying options such as the branch to deploy to, the repository URL, and user information for the commit.
const ghpages = require('gh-pages');
ghpages.publish('dist', {
branch: 'custom-branch',
repo: 'https://github.com/user/repo.git',
user: {
name: 'Your Name',
email: 'your-email@example.com'
}
}, function(err) {
if (err) {
console.error('Deployment failed:', err);
} else {
console.log('Deployment successful!');
}
});
Cleaning Up Before Deployment
This feature allows you to clean up the local cache before deploying. This can be useful to ensure that no old files are left over from previous deployments.
const ghpages = require('gh-pages');
ghpages.clean();
ghpages.publish('dist', function(err) {
if (err) {
console.error('Deployment failed:', err);
} else {
console.log('Deployment successful!');
}
});
Netlify CLI is a command-line tool for interacting with Netlify's platform. It allows you to deploy sites, manage DNS settings, and more. Unlike gh-pages, which is specific to GitHub Pages, Netlify CLI provides a broader range of functionalities for deploying and managing static sites on Netlify.
Surge is a simple command-line tool for publishing static sites. It offers a straightforward way to deploy sites to Surge's hosting service. While gh-pages is specific to GitHub Pages, Surge provides an alternative hosting solution with its own set of features and simplicity.
Vercel CLI is a command-line tool for deploying projects to Vercel's platform. It supports a wide range of frameworks and static site generators. Compared to gh-pages, Vercel CLI offers more advanced features such as serverless functions and automatic scaling.
Publish files to a gh-pages
branch on GitHub (or any other branch anywhere else).
npm install gh-pages --save-dev
This module requires Git >=1.7.6
.
var ghpages = require('gh-pages');
var path = require('path');
ghpages.publish(path.join(__dirname, 'dist'), function(err) { ... });
publish
ghpages.publish(basePath, callback);
// or...
ghpages.publish(basePath, options, callback);
Calling this function will create a temporary clone of the current repository, create a gh-pages
branch if one doesn't already exist, copy over all files from the base path, or only those that match patterns from the optional src
configuration, commit all changes, and push to the origin
remote.
If a gh-pages
branch already exists, it will be updated with all commits from the remote before adding any commits from the provided src
files.
Note that any files in the gh-pages
branch that are not in the src
files will be removed. See the add
option if you don't want any of the existing files removed.
basePath
string
The base directory for all source files (those listed in the src
config property).
Example use of the basePath
:
/**
* Given the following directory structure:
*
* build/
* index.html
* js/
* site.js
*
* The usage below will create a `gh-pages` branch that looks like this:
*
* index.html
* js/
* site.js
*
*/
ghpages.publish(path.join(__dirname, 'build'), callback);
The default options work for simple cases cases. The options described below let you push to alternate branches, customize your commit messages, and more.
string|Array<string>
'**/*'
The minimatch pattern or array of patterns used to select which files should be published.
boolean
false
Include dotfiles. By default, files starting with .
are ignored unless they are explicitly provided in the src
array. If you want to also include dotfiles that otherwise match your src
patterns, set dotfiles: true
in your options.
Example use of the dotfiles
option:
/**
* The usage below will push dotfiles (directories and files)
* that otherwise match the `src` pattern.
*/
ghpages.publish(path.join(__dirname, 'dist'), { dotfiles: true }, callback);
boolean
false
Only add, and never remove existing files. By default, existing files in the target branch are removed before adding the ones from your src
config. If you want the task to add new src
files but leave existing ones untouched, set add: true
in your options.
Example use of the add
option:
/**
* The usage below will only add files to the `gh-pages` branch, never removing
* any existing files (even if they don't exist in the `src` config).
*/
ghpages.publish(path.join(__dirname, 'build'), { add: true }, callback);
string
By default, gh-pages
assumes that the current working directory is a git repository, and that you want to push changes to the origin
remote.
If instead your script is not in a git repository, or if you want to push to another repository, you can provide the repository URL in the repo
option.
Example use of the repo
option:
/**
* If the current directory is not a clone of the repository you want to work
* with, set the URL for the repository in the `repo` option. This usage will
* push all files in the `src` config to the `gh-pages` branch of the `repo`.
*/
ghpages.publish(path.join(__dirname, 'build'), {
repo: 'https://example.com/other/repo.git'
}, callback);
string
'gh-pages'
The name of the branch you'll be pushing to. The default uses GitHub's gh-pages
branch, but this can be configured to push to any branch on any remote.
Example use of the branch
option:
/**
* This task pushes to the `master` branch of the configured `repo`.
*/
ghpages.publish(path.join(__dirname, 'build'), {
branch: 'master',
repo: 'https://example.com/other/repo.git'
}, callback);
string
'origin'
The name of the remote you'll be pushing to. The default is your 'origin'
remote, but this can be configured to push to any remote.
Example use of the remote
option:
/**
* This task pushes to the `gh-pages` branch of of your `upstream` remote.
*/
ghpages.publish(path.join(__dirname, 'build'), {
remote: 'upstream'
}, callback);
string
''
Create a tag after committing changes on the target branch. By default, no tag is created. To create a tag, provide the tag name as the option value.
string
'Updates'
The commit message for all commits.
Example use of the message
option:
/**
* This adds commits with a custom message.
*/
ghpages.publish(path.join(__dirname, 'build'), {
message: 'Auto-generated commit'
}, callback);
Object
null
If you are running the gh-pages
task in a repository without a user.name
or user.email
git config properties (or on a machine without these global config properties), you must provide user info before git allows you to commit. The options.user
object accepts name
and email
string values to identify the committer.
Example use of the user
option:
ghpages.publish(path.join(__dirname, 'build'), {
user: {
name: 'Joe Code',
email: 'coder@example.com'
}
}, callback);
string
gh-pages
directoryPath to a directory where your repository will be cloned. If this directory doesn't already exist, it will be created. If it already exists, it is assumed to be a clone of your repository.
Example use of the clone
option:
/**
* If you already have a temp directory, and want the repository cloned there,
* use the `clone` option as below. To avoid re-cloning every time the task is
* run, this should be a directory that sticks around for a while.
*/
ghpages.publish(path.join(__dirname, 'build'), {
clone: 'path/to/tmp/dir'
}, callback);
boolean
true
Push branch to remote. To commit only (with no push) set to false
.
Example use of the push
option:
ghpages.publish(path.join(__dirname, 'build'), { push: false }, callback);
boolean
false
Suppress logging. This option should be used if the repository URL or other information passed to git commands is sensitive and should not be logged. With silent true
log messages are suppressed and error messages are sanitized.
Example use of the silent
option:
/**
* This configuration will suppress logging and sanitize error messages.
*/
ghpages.publish(path.join(__dirname, 'build'), {
repo: 'https://' + process.env.GH_TOKEN + '@github.com/user/private-repo.git',
silent: true
}, callback);
function(string)
function(){}
Logger function. The default logging function is a no-op, allowing you to provide a custom logging implementation.
Example use of the logger
option:
/**
* This configuration will log to the console
*/
ghpages.publish(path.join(__dirname, 'build'), {
logger: function(message) {
console.log(message);
}
}, callback);
string
'git'
Your git
executable.
Example use of the git
option:
/**
* If `git` is not on your path, provide the path as shown below.
*/
ghpages.publish(path.join(__dirname, 'build'), {
git: '/path/to/git'
}, callback);
Installing the package creates a gh-pages
command line utility. Run gh-pages --help
to see a list of supported options.
With a local install of gh-pages
, you can set up a package script with something like the following:
"scripts": {
"deploy": "gh-pages -d dist"
}
And then to publish everything from your dist
folder to your gh-pages
branch, you'd run this:
npm run deploy
Note that this plugin requires Git 1.7.6 or higher (because it uses the --exit-code
option for git ls-remote
). If you'd like to see this working with earlier versions of Git, please open an issue.
v0.12.0
FAQs
Publish to a gh-pages branch on GitHub (or any other branch on any other remote)
The npm package gh-pages receives a total of 312,859 weekly downloads. As such, gh-pages popularity was classified as popular.
We found that gh-pages demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Critics call the Node.js EOL CVE a misuse of the system, sparking debate over CVE standards and the growing noise in vulnerability databases.
Security News
cURL and Go security teams are publicly rejecting CVSS as flawed for assessing vulnerabilities and are calling for more accurate, context-aware approaches.
Security News
Bun 1.2 enhances its JavaScript runtime with 90% Node.js compatibility, built-in S3 and Postgres support, HTML Imports, and faster, cloud-first performance.